home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc™ Source Code / Storage / Bento / CM / ValueRtn.h < prev   
Encoding:
C/C++ Source or Header  |  1996-08-28  |  7.5 KB  |  182 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        ValueRtn.h
  3.  
  4.     Contains:    Container Manager Common Value Routines Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1992-1996 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     8/22/96    EL        1376276: add cmDeleteToTmpFree.
  15.          <2>     8/26/94    EL        #1182275 Container merging.
  16.          <2>      6/3/94    EL        Rename Values.h/c to ValueRtn.h/c.
  17.          <1>      2/3/94    EL        first checked in
  18.  
  19.     To Do:
  20. */
  21.  
  22. /*---------------------------------------------------------------------------*
  23.  |                                                                           |
  24.  |                          <<<   ValueRtn.h    >>>                          |
  25.  |                                                                           |
  26.  |             Container Manager Common Value Routines Interfaces            |
  27.  |                                                                           |
  28.  |                               Ira L. Ruben                                |
  29.  |                                  7/22/92                                  |
  30.  |                                                                           |
  31.  |                     Copyright Apple Computer, Inc. 1992-1996              |
  32.  |                           All rights reserved.                            |
  33.  |                                                                           |
  34.  *---------------------------------------------------------------------------*
  35.  
  36.  This file contains the interfaces to the various routines needed for value operations,
  37.  e.g., CMWriteValueData() CMDeleteValueData(), etc.  Some of these routines are used when
  38.  applying updates at open time (insert and delete data, move a value header).
  39. */
  40.  
  41. #ifndef __VALUEROUTINES__
  42. #define __VALUEROUTINES__
  43.  
  44.  
  45. #ifndef __CMTYPES__
  46. #include "CMTypes.h"
  47. #endif
  48. #ifndef __CM_API_TYPES__
  49. #include "CMAPITyp.h"
  50. #endif
  51.  
  52. struct TOCValueHdr;
  53. struct TOCValue;
  54. struct TOCObject;
  55.  
  56.  
  57.                                                                     CM_CFUNCTIONS
  58.  
  59.  
  60. struct TOCValue *cmGetStartingValue(struct TOCValueHdr *theValueHdr,
  61.                                                                       CM_ULONG startingOffset, 
  62.                                                                         CM_ULONG *valueOffset);
  63.     /*
  64.     This returns the TOCValuePtr to the value entry which contains the stream starting 
  65.     offset, startingOffset.  Also returned in valueOffset is the offset within the returned
  66.     value entry which is the startingOffset'th byte.
  67.     
  68.     Note, NULL is returned for the value pointer if we cannot find the offset. This could 
  69.     happen when the startingOffset is beyond the end of the value.
  70.     
  71.     This routine is necessary because of continued values which are represented by a list of
  72.     TOCValue entries off of a TOCValueHdr.  Each entry represents a discontinous segment of
  73.     the value data which is always viewed as a stream of contiguous bytes even though they 
  74.     are not.  This routine is one of those that allows its caller to view the stream as
  75.     contiguous.
  76.     */
  77.     
  78.  
  79. CM_ULONG cmRead1ValueData(struct TOCValue *theValue, CM_UCHAR *buffer,
  80.                                                     CM_ULONG offset,CM_ULONG maxSize);
  81.     /*
  82.     This routine copies the data for the specified value (NOT a value header -- continued
  83.     values are not worried about here), starting at the specified offset, TO the caller's
  84.     buffer.  A maximum of maxSize characters or the size of the data, which ever is smaller,
  85.     is copied.  The function returns the amount of data copied to the buffer.
  86.     
  87.     Note, this routine handles the special cases for immediate data.
  88.     */
  89.  
  90.  
  91. CM_ULONG cmOverwrite1ValueData(struct TOCValue *theValue, CM_UCHAR *buffer,
  92.                                                              CM_ULONG offset, CM_ULONG size);
  93.     /*
  94.     This routine copies the data for the specified value (NOT a value header -- continued
  95.     values are not worried about here), starting at the specified offset, FROM the caller's
  96.     buffer. A maximum of size characters are overwritten to the value.  The function returns
  97.     the amount of data copied from the buffer to the value.
  98.     
  99.     Note, overwriting of global names is NOT allowed and assumed not passed to this routine.
  100.     Immediates are, however, handled and can be overwritten up to their existing size.
  101.     */
  102.     
  103.     
  104. CMBoolean cmConvertImmediate(struct TOCValue *theValue);
  105.     /*
  106.     This routine is called whenever an immediate data value must be converted to a
  107.     non-immediate.  It takes as parameters the pointer to the immediate value and returns
  108.     true if there are no errors.  On return the value will have been converted to a
  109.     non-immediate and the input segment CMValue changed to container the offset to the 
  110.     now written value.
  111.     */
  112.     
  113.     
  114. struct TOCValue *cmInsertNewSegment(struct TOCValueHdr *theValueHdr,
  115.                                                                          struct TOCValue *insBeforeValue,
  116.                                                                           CM_ULONG segOffset, CM_ULONG dataOffset,
  117.                                                                          CMSize size);
  118.     /*
  119.     This routine is called by CMInsertValueData() to create a new value segment insert to be
  120.     inserted into a previously existing value.  It is also called when applying data insert
  121.     updates at open time (by the internal routine applyValueUpdateInstructions() in 
  122.      Update.c ).  The new insert data is already written to the (updating) container, and the
  123.     data is at container offset dataOffset.  It is size bytes long.  The insert is to be at
  124.     the specified segOffset within the value segment insBeforeValue. 
  125.     
  126.     The function returns a pointer to the newly created insert segment, or NULL if there is
  127.     an error and the error reporter returns.
  128.  
  129.     Note, this routine is for non-immediate data insertions only.  CMInsertValueData() 
  130.     handles insertions on immediates.  For updating, immediates are handled differently and
  131.     thus can't get in here.
  132.     */
  133.     
  134.     
  135. void cmDeleteSegmentData(struct TOCValueHdr *theValueHdr, CM_ULONG startOffset,
  136.                                                  CM_ULONG endOffset);
  137.     /*
  138.     This routine is called by CMDeleteValueData() to delete value data  It is also called
  139.     when applying data deletion updates at open time (by the internal routine
  140.     applyValueUpdateInstructions() in  Update.c ).  All the data starting at offset 
  141.     startOffset, up to and including the end offset, endOffset, are to be deleted.  If the
  142.     start and end offsets span entire value segments, those segments are removed.
  143.  
  144.     Note, this routine is for non-immediate data deletions only.  CMDeleteValueData() handles
  145.     deletions on immediates.  For updating, immediates are handled differently and thus can't
  146.     get in here.
  147.     */
  148.     
  149.     
  150. struct TOCValueHdr *cmMoveValueHdr(struct TOCValueHdr *theFromValueHdr, CMObject object,
  151.                                                                                                                                                   CMProperty property);
  152.     /*
  153.     This routine is called by CMMoveValueData() to move a value (header).  It is also called
  154.     when applying "inserted" (move) updates at open time (by the internal routine
  155.     applyValueUpdateInstructions() in  Update.c ).   The value is physically deleted from its
  156.     original object/property as if a CMDeleteValue() were done on it.  If the value deleted
  157.     is the only one for the property, the property itself is deleted as in
  158.     CMDeleteObjectProperty(). 
  159.     
  160.     The value is added to the "to"s object propery in a manner similar to a CMNewValue(). The
  161.     order of the values for both the value's original object property and for the value's
  162.     new object property may be changed.
  163.  
  164.     Note, that although the effect of a move is a combination CMDeleteValue()/CMNewValue(),
  165.     THE INPUT REFNUM REMAINS VALID!  Its association is now with the new object property.
  166.  
  167.   The input refNum is returned as the function result.  NULL is returned if there is an 
  168.   error and the error reporter returns.
  169.     */
  170.     
  171. void cmDeleteToTmpFree(struct TOCValueHdr* theValueHdr, CMCount offset, CMSize size);
  172.  
  173. /*
  174.  
  175.  Deletes size bytes from the value data starting at the offset.  Always put it on
  176.  the temp free list.
  177.  
  178. */
  179.  
  180.                                                           CM_END_CFUNCTIONS
  181. #endif
  182.